Unless you have some advanced or unusual requirements, template loading is very straight forward. The simple description is this:

Templates, by default, are always FreeMarker templates and are loaded the same way other FreeMarker templates (such as your results) are: by first searching the web application and then the classpath.

Template and Themes

Templates are loaded based on the theme (see Selecting Themes) and the template directory. The template directory is defined by the webwork.ui.templateDir property in webwork.properties (defaults to template). This means, by default, if a tag is using the ajax theme, the following two locations will be searched (in this order):

  1. In the web app: /template/ajax/template.ftl
  2. In the classpath: /template/ajax/template.ftl

Overriding Templates

Because most of the templates you will need are included in the WebWork jar (the classpath), you may find a few situations where you need to override a particular template to provide behavior that is unique to your application. For example, you might wish to change how select tags render. Rather than creating a brand new template and changing every tag to use that template, you can override the built in select.ftl template by copying the file from in the jar over to a new /template/xhtml/select.ftl directory.

Altering Template Loading Behavior

Sometimes it may be important to load templates from elsewhere other than the classpath and web app. For example, you might wish to load templates from the file system or a URL. This is useful for not only HTML Tags, but also for any result your write.

You can do this by consulting the FreeMarker documentation and extending the FreeMarkerManager.

Alternative Template Engines

WebWork provides for template rendering engines other than FreeMarker. We almost never recommend using anything other than FreeMarker templates, if only because WebWork provides templates already written in FreeMarker and not in JSP or Velocity. However, some users, especially advanced users of older versions of WebWork (pre-2.2) may find it necessary to use a different template engine.

Alternative template engines are for advanced users. Please use with care!

WebWork supports three template engines, which can be controlled by the webwork.ui.templateSuffix in webwork.properties:

  • ftl (default) - FreeMarker-based template engine
  • vm - Velocity-based template engine
  • jsp - JSP-based template engine

If you choose to use vm or jsp, you must implement your own templates and themes entirely, which is a large amount of work.

Just because your views aren't written in FreeMarker doesn't mean you can't use the FreeMarker template engine. Again, we strongly discourage you from writing your own templates from scratch. Rather, we recommend you learn a small bit of FreeMarker and extend existing templates